home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / EDITORS / LINEEDIT / !LineEdit / !ReadMe next >
Text File  |  1991-01-03  |  12KB  |  285 lines
  1. Documentation for Line Editor Module V2.30
  2. ------------------------------------------
  3.  
  4. *********************  Very boring Copyright Notice  ********************
  5. *                                                                       *
  6. * The source code, binary and documentation for the Line Editor are the *
  7. * exclusive copyright of Richard K. Lloyd and are freely distributable, *
  8. *                  provided this notice is left intact.                 *
  9. *                                                                       *
  10. *************************************************************************
  11.  
  12. Introduction
  13. ------------
  14.  
  15. For compatibility with the BBC Micro command line, Acorn has kept the
  16. COPY key method of repeating a previous command when developing the OS_ReadLine
  17. interface for the Archimedes. As far as I can see, the COPY key method has only
  18. ONE advantage - it's easy to join bits of text together from different lines on
  19. the screen. It has NO OTHER ADVANTAGES, so I set about fixing this by writing
  20. a command history interface to OS_ReadLine as a module. So what extra goodies
  21. does this give you over the COPY key system ? Here's a list...
  22.  
  23.     * Lines can be recalled long after they have disappeared from the screen
  24.     * Editing is possible in the middle of a line rather than just at the end
  25.     * Insert & overtype mode are available (now reflected in the cursor shape)
  26.     * Shift-delete deletes to the right (impossible with the COPY system)
  27.     * Lines can be recalled by matching their start uniquely (using ~substring)
  28.     * Up to 255 lines can recalled and only unique lines are stored
  29.     * Cursor navigation can use Shift or Ctrl to jump words or to edge of line
  30.     * Optional reversion to the COPY system if you need it for a single line
  31.     * The Line Editor is the ONLY Archimedes program I know of that supports
  32.       filename completion
  33.  
  34. Machine Requirements
  35. --------------------
  36.  
  37. The LineEditor module can be run on ANY Archimedes with (typically) 12K
  38. of RMA to spare and will remain active after a soft reset, whereas the
  39. !RunImage front-end requires RISC OS and 24K of application workspace
  40. (on top of the 12K of RMA needed for the module) and currently doesn't
  41. survive a soft reset or Desktop exit.
  42.  
  43. Distribution Files inside the !LineEdit directory
  44. -------------------------------------------------
  45.  
  46. 1.  !LineEdit.!ReadMe    - This file
  47. 2.  !LineEdit.!Run       - Installs Line Editor and runs !RunImage front-end
  48. 3.  !LineEdit.!RunImage  - BASIC Desktop front-end for setting EdSize/EdLines
  49. 4.  !LineEdit.!Sprites   - Silly Line Editor icon for the Desktop
  50. 5.  !LineEdit.CompDoc    - Documentation for Filename Completion
  51. 6.  !LineEdit.Completion - Library source code for Filename Completion
  52. 7.  !LineEdit.EditSrc    - Line Editor module main source code
  53. 8.  !LineEdit.Example    - Example BASIC/ARM program to use Completion code
  54. 9.  !LineEdit.History    - Separate Revision History file for the Line Editor
  55. 9.  !LineEdit.LineEditor - Assembled Line Editor module binary
  56. 10. !LineEdit.Templates  - Template file (!FormEd-created) for Info dialogue
  57.  
  58. V2.20 onwards now comes with a very 'noddy' front-end for the configuration of
  59. the EdCursor, EdSize and EdLines values - just double-click on the !LineEdit
  60. icon inside the Desktop and the values can be changed from the menu of the icon
  61. bar icon. The *EdStatus, *Recall and *EraseHistory commands are also on the
  62. same menu for ease of use.
  63.  
  64. Note: Quitting this front-end via its own Quit menu option will *RMKill
  65.       the Line Editor module. Quitting with Shift-Ctrl-f12 or via the
  66.       Task Manager Task Quit, however, does NOT *RMKill the module.
  67.  
  68. To reassemble the Line Editor (preferably outside the Desktop - I wish that
  69. opening a Filer window would change the current directory to that window !),
  70. *Dir into the !LineEdit directory and then type '*EditSrc'.
  71.  
  72. Note: If you exclusively use the Line Editor OUTSIDE the Desktop, then you'll
  73.       only need !LineEdit.LineEditor, so copy that into your Library directory
  74.       and start it up by typing '*LineEditor'. However, it you do start the
  75.       Line Editor module outside of the Desktop, then the *Configure EdSize
  76.       value should not exceed the amount of free RMA available.
  77.  
  78. Because the Line Editor traps the OS_ReadLine vector, the following will be
  79. intercepted :
  80.  
  81. a) BASIC's immediate command mode (prompted by a ">").
  82. b) BASIC's INPUT and INPUT LINE statements.
  83. c) The Supervisor's line input (default prompt is a "*").
  84. d) Any ARM code or 6502-emulated code (inc. BASIC 4.31) that calls OS_Word 0.
  85. e) Any ARM code that calls OS_ReadLine (a bit obvious this one...).
  86.  
  87. The *Configure EdCursor command
  88. -------------------------------
  89.  
  90. Syntax: *Configure EdCursor <value>
  91.  
  92. This command sets the type of text cursor shown when the Line Editor is active.
  93.  
  94. Possible legal values are:
  95. 0   ->    Flashing & underline  (Default system cursor)
  96. 1   ->    Flashing & block
  97. 2   ->    Steady   & underline
  98. 3   ->    Steady   & block
  99.  
  100. The new value is saved to bits 6 and 7 of battery-backed RAM location 38 and
  101. takes effect immediately. Note that the toggling of Insert/Overtype mode with
  102. the use of the Insert key now toggles the shape of cursor too (between
  103. underline and block). When the Line Editor module is killed, the default system
  104. cursor (value = 0 above) is restored.
  105.  
  106. The *Configure EdLines command
  107. ------------------------------
  108.  
  109. Syntax: *Configure Edlines <lines>
  110.  
  111. This command sets the number of lines in the command history buffer. If the
  112. parameter is outside the range 2 to 255 lines, then a default value of 30
  113. lines is used instead. The new value is saved to battery-backed RAM location
  114. 37 and takes effect immediately (may clear command history buffer).
  115.  
  116. The *Configure EdSize command
  117. -----------------------------
  118.  
  119. Syntax: *Configure EdSize <kilobytes>
  120.  
  121. This command sets the size of the command history buffer. The parameter states
  122. the number of kilobytes that are to be allocated. If it is outside the range
  123. 1 to 63 kilobytes, then a default value of 4 kilobytes is used instead. The
  124. new value is saved to bits 0 to 5 of battery-backed RAM location 38 and takes
  125. effect immediately (may clear command history buffer).
  126.  
  127. The *EdStatus command
  128. ---------------------
  129.  
  130. Syntax: *EdStatus
  131.  
  132. This command displays a table of the CURRENT command history usage. Of course,
  133. typing this command will change the values !
  134.  
  135. The *EraseHistory command
  136. -------------------------
  137.  
  138. Syntax: *EraseHistory
  139.  
  140. This command clears the command line history buffer. It is provided for use
  141. inside programs rather than actually at the command line itself, because
  142. Ctrl-Delete is a lot easier to type...
  143.  
  144. The *Recall command
  145. -------------------
  146.  
  147. Syntax: *Recall
  148.  
  149. This command displays the current contents of the command history buffer.
  150.  
  151. Line Editor Controls (the list below can be displayed with "*Help Editor")
  152. --------------------
  153.  
  154. The keys supported in the Line Editor are as follows :
  155. Escape or Ctrl-[    : Abandon current line and do not insert in buffer.
  156. Tab or Ctrl-I       : Filename completion (beeps if no unique match).
  157. Insert              : Toggle insert and overtype modes for one line only.
  158. Copy                : Allow normal screen copying for one line only.
  159. Shift-Insert        : Clear and remove single line from history.
  160. Shift-Delete        : Delete character directly under cursor.
  161. Ctrl-Delete         : Clear line and erase entire history.
  162. Cursor Up           : Cycle backwards through previous commands.
  163. Cursor Down         : Cycle forwards through previous commands.
  164. Cursor Left         : Move cursor one character to the left.
  165. Cursor Right        : Move cursor one character to the right.
  166. Shift-Cursor Left   : Move cursor to end of previous word.
  167. Shift-Cursor Right  : Move cursor to start of next word.
  168. Ctrl-Cursor Up      : Recall the oldest previous command.
  169. Ctrl-Cursor Down    : Recall the newest previous command.
  170. Ctrl-Cursor Left    : Move cursor to start of line.
  171. Ctrl-Cursor Right   : Move cursor to end of line.
  172. Backspace or Ctrl-H : Identical to Delete.
  173. Ctrl-J or Ctrl-M    : Identical to Return.
  174. Ctrl-U              : Clear entire line.
  175. All other control codes are echoed to the screen, but not put in buffer.
  176. ~<substring> recalls command whose start uniquely matches <substring>.
  177.  
  178. Filename Completion
  179. -------------------
  180.  
  181. Please read the "CompDoc" document for details.
  182.  
  183. Substring Recall
  184. ----------------
  185.  
  186. A new feature with V1.02 onwards is the ~<substring> facility. This recalls a
  187. particular command, providing the start of the command matches <substring>
  188. UNIQUELY (take note, Gary !).
  189.  
  190. For example, if the following commands were typed in:
  191.  
  192. Command 1 - *Help Commands
  193. Command 2 - *Mount 0
  194. Command 3 - *Info *
  195. Command 4 - PRINT"HELLO"
  196.  
  197. Then the ~<substring> system could be used as follows:
  198.  
  199. ~P         would recall PRINT"HELLO"
  200. ~*M        would recall *Mount 0
  201. ~*h        would recall *Help Commands because the system is case insensitive
  202. ~*         would leave the ~* in place because there is no unique match
  203. ~*Z        would leave the ~*Z in place because there is no match at all
  204. ~*Info *.c would leave the ~*Info *.c in place because the command string
  205.            is longer than *Info *
  206.  
  207. Note: The last example is clearly a recalled command that's been edited,
  208. because normally expansion would have taken place after the ~*I had been typed.
  209.  
  210. If there is no recall match when RETURN is pressed, then the leading tildes
  211. are stripped off and the command is executed as if the tildes weren't specified
  212. at all.
  213.  
  214. This recall system is roughly based on the !! system of some UN*X shells, but
  215. is better in my opinion because it expands BEFORE RETURN IS PRESSED.
  216.  
  217. History Buffer Management
  218. -------------------------
  219.  
  220. There is a (now nice) piece of logic in the Line Editor code that will purge
  221. the oldest commands if the command history is almost full. If a line is typed
  222. in which already duplicates one in the command history, then the latter is
  223. removed and the duplicate line is put in the last command history slot.
  224.  
  225. Memory Usage (changed with V2.21 onwards)
  226. ------------
  227.  
  228. Type        1 Unit   Min. Units  Max. Units  Default Units  CMOS RAM
  229. ====     ==========  ==========  ==========  =============  ========
  230. EdLines     4 bytes      2          255           30         Loc 37
  231. EdSize   1024 bytes      1           63            4         Loc 38 (bits 0-5)
  232.  
  233. Hence the default memory usage (claimed from the RMA) is:
  234.  
  235. EdLines    = 30 *    4 =  120
  236. EdSize     =  4 * 1024 = 4096
  237. Completion = 77 *   12 =  924
  238.                  Total = 5140 bytes
  239.  
  240. The Line Editor vs. The !Edit Task Window
  241. -----------------------------------------
  242.  
  243. Unlike versions prior to V2.20, the Line Editor now co-exists with the !Edit
  244. Task Window without crashing the machine. HOWEVER, I've discovered that trying
  245. killing the !Edit Task Window with the Line Editor installed DOES NOT actually
  246. kill that Task Window and it cannot be killed without shutting down the
  247. Desktop !
  248.    My advice is to avoid the combination of the two if at all possible because
  249. the Line Editor isn't available inside the !Edit Task Window anyway. If you
  250. really *must* run the two together, then twiddle the 'Next' memory bar in the
  251. Task Manager to, say, 80K or 100K otherwise ALL of the application memory will
  252. be grabbed when you next select 'Create Task Window' in !Edit - hence locking
  253. out that memory because of the clash.
  254.  
  255. The Line Editor vs. Twin Tasks
  256. ------------------------------
  257.  
  258. Again, V2.20 onwards of the Line Editor is a lot more stable than the previous
  259. versions and will not crash the machine during a Twin background task.
  260. HOWEVER, strange behaviour (due to a mixture of command recall and Twin
  261. editing) can occur if arrow keys are used during a Twin background task.
  262.  
  263. Revision History
  264. ----------------
  265.  
  266. Please read the "History" document for details.
  267.  
  268. Future Improvements to Line Editor V2.30
  269. ----------------------------------------
  270.  
  271. Only bug-fix releases are planned from now on. If someone suggests a new
  272. feature that's easy to implement, then I may consider it but otherwise I
  273. intend to freeze this core of this project at V2.30.
  274.  
  275. Where to find me to report bugs or improvements to the Line Editor
  276. ------------------------------------------------------------------  
  277.  
  278. Snail Mail           JANET e-mail
  279. ----------           ------------
  280. Richard K. Lloyd,    rkl@uk.ac.liv.cs.and
  281. 1, Banks Road,
  282. Lower Heswall,
  283. Wirral,
  284. Merseyside. 
  285.